ComboBox 1.1.1
                              External Area Package

Overview

The idea behind ComboBox is to provide an easy way for users to choose an item from a list.  4th Dimension provides Choice Lists for this purpose, but the current implementation has several problems:

¥	The window containing the list of valid choices is physically separated from the layoutÕs enterable area.  This causes a distraction as users must shift their focus from between two very different areas of the screen.
¥	The programmer has no control over the location of the choice list window or the appearance of the text in the window.
¥	Unless the list is sorted, users cannot simply type the entries they wish, even if they know what they are looking for.
¥	Even after a choice has been made, users can still modify the selected text to become something that is not in the list.  This ability is not always desireable.
¥	The list of choices must reside in a 4D list, which is maintained on the server (in a multi-user environment).  Any other user on the entire system can change this list even while it is in use.

ComboBox addresses these user-related problems while providing a programming interface that allows the area to adapt to practically any look and feel the designer wishes.

This package contains two copies of ComboBox.  ComboBox.Lib uses the drag-and-drop, platform-independent extension architecture, and requires 4th Dimension 3.2.5 or greater or 4D Client and 4D Server 1.2.5 or greater.  ComboBox.Ext can be installed using the 4D External Mover, and is for use with versions of 4th Dimension prior to 3.2.5.  Both copies of ComboBox require System 7.0 or greater.

NOTE: It is extremely important that you do not include both copies of ComboBox for use with the same structure.  You should either install ComboBox.Ext using the 4D External Mover, or install ComboBox.Lib by dragging it into the Mac4DX folder, but not both.

Source Code

For those who are interested, source code for the ComboBox external area is now available.  Look for it in the archive from which you received this package.  The ComboBox Source package includes all C source code files, resource files, and Metrowerks¨ CodeWarriorª Gold 7 project files necessary to build the FAT version of the ComboBox external area.  You will need to obtain the Platform- Independent Extension Authoring Kit from ACI or your local affiliate for the required header files.

Copyright Information

The ComboBox external area package and this document are copyright ©1995Ð1996 by Pensacola Christian College, Inc., 250 Brent Lane, Pensacola, FL  32503.  All trademarks referenced in this document are property of their respective holders.

License

This external area package is provided free of charge by Pensacola Christian College.  You may use it in as many database applications as you desire.  You may not sell it by itself or with any other group/bundle/collection of extensions, framework, shell, etc.  It is provided free of charge, so donÕt sell it for its own sake.  Although you may distribute ComboBox freely, you may not charge any fee for the use, copying, or distribution of the product.  Pensacola Christian College maintains ownership of the ComboBox external area package as well as this documentation.

If the text of this document, or any portion thereof, is duplicated and distributed by any means Ñ physical, electronic, or otherwise Ñ such duplication and distribution must include the text of this document in its entirety and unaltered.  No fee may be charged for the for the duplication or distribution of the ComboBox external area or of this document.

By using or distributing ComboBox, you agree to this license and to the ÒNo WarrantyÓ section below.

No Warranty

PENSACOLA CHRISTIAN COLLEGE MAKES NO WARRANTY, EXPRESS OR IMPLIED, WITH RESPECT TO THIS SOFTWARE, ITS QUALITY, PERFORMANCE, OR FITNESS FOR A PARTICULAR PURPOSE.  THIS SOFTWARE IS PROVIDED ÒAS IS,Ó AND YOU, THE CONSUMER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE.

IN NO EVENT WILL PENSACOLA CHRISTIAN COLLEGE AND/OR ANY OF ITS EMPLOYEES BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT IN THE SOFTWARE OR ITS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  IN PARTICULAR, NEITHER PENSACOLA CHRISTIAN COLLEGE NOR ANY OF ITS EMPLOYEES SHALL HAVE ANY LIABILITY FOR ANY HARDWARE, PROGRAMS OR DATA STORED IN OR USED WITH THIS PRODUCT, INCLUDING THE COSTS OF RECOVERING OR REPLACING SUCH HARDWARE, PROGRAMS OR DATA.

Acknowlegements

The behavior of the ComboBox external area package is based in part on the combo box from Microsoft¨ Windowsª and the AppleDirections articles ÒThe Joys of Disambiguating,Ó March 1995, pp. 14-15, and ÒThe Joys of Disambiguating, Part Two,Ó April 1995, pp. 14-16, by Peter Bickford.

Thanks to Dan Katz for providing the original ComboBox_DB database.

Thanks also to the members of the 4D list on the internet.  To subscribe to the 4D list, send email to 4d-nug@liststar.fsti.com with the word ÒsubscribeÓ in the subject of your message.

Most importantly, thanks to Jesus Christ for answering many ÒIÕm stuck, Lord;  please show me how to do this!Ó prayers, and for guiding me to the resources I needed to find the answers.

Comments

Send comments to Steve_Dwire@linq.pcci.edu.

About Pensacola Christian College

For more information about Pensacola Christian College and its related ministries, send e-mail to pccinfo@pcci.edu or visit our home page at http://www.pcci.edu.




Default Commands


CB_SetDefTxtFnt (FontNum; FontSize; FontStyle)

Sets the default font, size, and style for the text areas.

FontNum	Integer: The number of the font to use for displaying the text.  (DefaultÊ=Ê1Ê{Geneva})

FontSize	Integer: The size, in points, to use for displaying the text.  (Default = 9)

FontStyle	Integer: The sum of the following style attributes to use for displaying the text:

	0	Plain
	1	Bold
	2	Italics
	4	Underline
	8	Outline
	16	Shadow
	32	Condensed
	64	Extended

	(Default = 0 {Plain})


CB_SetDefTxtCol (ForeColor; BackColor)

Sets the default colors for the text areas.

ForeColor	Integer: The number (0-255) of the color from 4DÕs palette to use for the text foreground.  (Default = 15 {Black})

BackColor	Integer: The number (0-255) of the color from 4DÕs palette to use for the text background.  (Default = 0 {White})


CB_SetDefLstFnt (FontNum; FontSize; FontStyle)

Sets the default font, size, and style for the lists.

FontNum	Integer: The number of the font to use for displaying the lists.  (DefaultÊ=Ê1Ê{Geneva})

FontSize	Integer: The size, in points, to use for displaying the lists.  (Default = 9)

FontStyle	Integer: The sum of the following style attributes to use for displaying the lists:

	0	Plain
	1	Bold
	2	Italics
	4	Underline
	8	Outline
	16	Shadow
	32	Condensed
	64	Extended

	(Default = 0 {Plain})


CB_SetDefLstCol (ForeColor; BackColor)

Sets the default colors for the lists.

ForeColor	Integer: The number (0-255) of the color from 4DÕs palette to use for the list foreground.  (Default = 15 {Black})

BackColor	Integer: The number (0-255) of the color from 4DÕs palette to use for the list background.  (Default = 0 {White})


CB_SetDefLstRws (Rows)

Sets the default number of rows to display in the scrolling lists.

Rows	Integer: The number of rows to display in the scrolling lists.  (Default = 5)


CB_SetDefPopPic (CUp; CDown; CDisabled; BUp; BDown; BDisabled)

Sets the default PICT resource IDs to use for the popup-indicator button.  Set these values to zero (0) if you do not wish to have a popup-indicator button.

CUp	Integer: PICT resource ID for the color picture of the popup-indicator button in the up (unpressed) position.

CDown	Integer: PICT resource ID for the color picture of the popup-indicator button in the down (pressed) position.

CDisabled	Integer: PICT resource ID for the color picture of the popup-indicator button when the area is disabled.

BUp	Integer: PICT resource ID for the black & white picture of the popup-indicator button in the up (unpressed) position.

BDown	Integer: PICT resource ID for the black & white picture of the popup-indicator button in the down (pressed) position.

BDisabled	Integer: PICT resource ID for the black & white picture of the popup-indicator button when the area is disabled.


CB_SetDefGap (PICTGap; TopGap; LeftGap; RightGap)

Sets the default sizes (in pixels) of the gaps to leave in certain positions when drawing the area.  ComboBox draws no boundaries of any kind around the popup-indicator button or the text area.  You should draw your own boundaries behind the external area and set these gap values to allow  those boundaries to show through the gaps.  This strategy allows you to make ComboBox conform to your systemÕs own look and feel.

PICTGap	Integer: The size of the gap between the popup-indicator button and the right edge of the text area.  (Default = 0)

TopGap	Integer: The size of the gap between the bottom of the external area and the top of the list window.  (Default = 3)

LeftGap	Integer: The size of the gap between the left edge of the external area and the left edge of the list window.  (Default = 1)

Right Gap	Integer: The size of the gap between the right edge of the external area and the right edge of the list window.  (Default = 0)


CB_SetDefLead (Leading)

Sets the default distance (in pixels) between the top of the external area and the top of the text area.

Leading	Integer: Distance between the top of the external area and the top of the text area.  (Default = 1)


CB_SetDefFlags (CanFind; CanFill; CanList; CanEdit; ListOnActivate; ListOnKey)

Sets the flags governing the default behavior of ComboBox areas.

CanFind	Integer: When the user presses a key, if CanFind is one (1), ComboBox will select the first item the in the list that begins with what the user has typed.  If CanFind is zero (0), ComboBox will not change the selection in the list.  (DefaultÊ=Ê1)

CanFill	Integer: When the user presses a key and ComboBox finds an item in the list that begins with what the user has typed, if CanFill is one (1), ComboBox will fill in the text area with the item from the list.  If CanFill is zero(0), ComboBox will not change the text area.  (Default = 1)

CanList	Integer: If CanList is one (1), ComboBox will display the list of choices when the user clicks on the popup-indicator button.  Clicking on the popup-indicator button when the list is open will close the list.  If CanList is zero (0), the list of choices will not be displayed.  (Default = 1)

CanEdit	Integer: If CanEdit is one (1), ComboBox will allow the user to edit the text in the text area.  ComboBoxÕs searching is based on the text found in the text area, and searching occurs only when the insertion point is at the end of the text.  Use this option if the user can choose items that are not in the list.  If CanEdit is zero (0), the user cannot edit or change the selection of the text in the text area.  ComboBoxÕs searching is based on the characters the user has typed.  The search string is reset whenever there is a pause in typing longer than the double-click time set in the Mouse Control Panel.  (Default = 0)

ListOnActivate	Integer: If ListOnActivate is one (1), the list of choices will appear whenever the external area is activated.  If ListOnActivate is zero (0), it will not.  Setting ListOnActivate to one (1) overrides CanList, and forces it to one (1).  (Default = 1)

ListOnKey	Integer: If ListOnKey is one (1), the list of choices will appear whenever the user types into the text area (see CanFind).  If ListOnKey is zero (0), it will not.  Setting ListOnKey to one (1) overrides CanList, and forces it to one (1).  (DefaultÊ=Ê1)




Area Commands


CB_SetTxtFnt (Area; FontNum; FontSize; FontStyle)

Sets the font, size, and style for a text area.

Area	LongInt: The area to change.

FontNum	Integer: The number of the font to use for displaying the text.

FontSize	Integer: The size, in points, to use for displaying the text.

FontStyle	Integer: The sum of the following style attributes to use for displaying the text:

	0	Plain
	1	Bold
	2	Italics
	4	Underline
	8	Outline
	16	Shadow
	32	Condensed
	64	Extended


CB_SetTxtCol (Area; ForeColor; BackColor)

Sets the colors for a text area.

Area	LongInt: The area to change.

ForeColor	Integer: The number (0-255) of the color from 4DÕs palette to use for the text foreground.

BackColor	Integer: The number (0-255) of the color from 4DÕs palette to use for the text background.


CB_SetLstFnt (Area; FontNum; FontSize; FontStyle)

Sets the font, size, and style for a list.

Area	LongInt: The area to change.

FontNum	Integer: The number of the font to use for displaying the list.

FontSize	Integer: The size, in points, to use for displaying the list.

FontStyle	Integer: The sum of the following style attributes to use for displaying the list:

	0	Plain
	1	Bold
	2	Italics
	4	Underline
	8	Outline
	16	Shadow
	32	Condensed
	64	Extended


CB_SetLstCol (Area; ForeColor; BackColor)

Sets the colors for a list.

Area	LongInt: The area to change.

ForeColor	Integer: The number (0-255) of the color from 4DÕs palette to use for the list foreground.

BackColor	Integer: The number (0-255) of the color from 4DÕs palette to use for the list background.


CB_SetLstRws (Area; Rows)

Sets the number of rows to display in the scrolling list.

Area	LongInt: The area to change.

Rows	Integer: The number of rows to display in the scrolling list.


CB_SetPopPic (Area; CUp; CDown; CDisabled; BUp; BDown; BDisabled)

Sets the PICT resource IDs to use for the popup-indicator button.  Set these values to zero (0) if you do not wish to have a popup-indicator button.

Area	LongInt: The area to change.

CUp	Integer: PICT resource ID for the color picture of the popup-indicator button in the up (unpressed) position.

CDown	Integer: PICT resource ID for the color picture of the popup-indicator button in the down (pressed) position.

CDisabled	Integer: PICT resource ID for the color picture of the popup-indicator button when the area is disabled.

BUp	Integer: PICT resource ID for the black & white picture of the popup-indicator button in the up (unpressed) position.

BDown	Integer: PICT resource ID for the black & white picture of the popup-indicator button in the down (pressed) position.

BDisabled	Integer: PICT resource ID for the black & white picture of the popup-indicator button when the area is disabled.


CB_SetGap (Area; PICTGap; TopGap; LeftGap; RightGap)

Sets the sizes (in pixels) of the gaps to leave in certain positions when drawing the area.  ComboBox draws no boundaries of any kind around the popup-indicator button or the text area.  You should draw your own boundaries behind the external area and set these gap values to allow  those boundaries to show through the gaps.  This strategy allows you to make ComboBox conform to your systemÕs own look and feel.

Area	LongInt: The area to change.

PICTGap	Integer: The size of the gap between the popup-indicator button and the right edge of the text area.

TopGap	Integer: The size of the gap between the bottom of the external area and the top of the list window.

LeftGap	Integer: The size of the gap between the left edge of the external area and the left edge of the list window.

Right Gap	Integer: The size of the gap between the right edge of the external area and the right edge of the list window.


CB_SetLead (Area; Leading)

Sets the distance (in pixels) between the top of the external area and the top of the text area.

Area	LongInt: The area to change.

Leading	Integer: Distance between the top of the external area and the top of the text area.  (Default = 1)


CB_SetFlags (Area; CanFind; CanFill; CanList; CanEdit; ListOnActivate; ListOnKey)

Sets the flags governing the behavior of a ComboBox area.

Area	LongInt: The area to change.

CanFind	Integer: When the user presses a key, if CanFind is one (1), ComboBox will select the first item the in the list that begins with what the user has typed.  If CanFind is zero (0), ComboBox will not change the selection in the list.

CanFill	Integer: When the user presses a key and ComboBox finds an item in the list that begins with what the user has typed, if CanFill is one (1), ComboBox will fill in the text area with the item from the list.  If CanFill is zero(0), ComboBox will not change the text area.

CanList	Integer: If CanList is one (1), ComboBox will display the list of choices when the user clicks on the popup-indicator button.  Clicking on the popup-indicator button when the list is open will close the list.  If CanList is zero (0), the list of choices will not be displayed.

CanEdit	Integer: If CanEdit is one (1), ComboBox will allow the user to edit the text in the text area.  ComboBoxÕs searching is based on the text found in the text area, and searching occurs only when the insertion point is at the end of the text.  Use this option if the user can choose items that are not in the list.  If CanEdit is zero (0), the user cannot edit or change the selection of the text in the text area.  ComboBoxÕs searching is based on the characters the user has typed.  The search string is reset whenever there is a pause in typing longer than the double-click time set in the Mouse Control Panel.

ListOnActivate	Integer: If ListOnActivate is one (1), the list of choices will appear whenever the external area is activated.  If ListOnActivate is zero (0), it will not.  Setting ListOnActivate to one (1) overrides CanList, and forces it to one (1).

ListOnKey	Integer: If ListOnKey is one (1), the list of choices will appear whenever the user types into the text area (see CanFind).  If ListOnKey is zero (0), it will not.  Setting ListOnKey to one (1) overrides CanList, and forces it to one (1).


CB_FillLst (Area;  ÒArrayNameÓ)

Fills the selected areaÕs list with the elements of a text array.

Area	LongInt: The area to change.

ArrayName	String: The name of the text array that holds the elements that belong in the areaÕs list.  The array must be either a process array or an interprocess array.  No local arrays are allowed.


CB_UpdateLst (Area)

Updates the listÕs internal data to reflect any changes in the array specified with CB_FillLst.  Call CB_UpdateLst whenever you make a change to your array.

Area	LongInt: The area to change.


CB_SetLstPos (Area; Position)

Selects a particular item in an areaÕs list.  CB_SetLstPos also changes the text of the text area to reflect the item selected in the list.

Area	LongInt: The area to change.

Position	Integer: The element number to select in the list.


CB_SetTxt (Area; Text)

Sets the text of the text area.  If you wish to set the text area to reflect a certain element of the list, use CB_SetLstPos.

Area	LongInt: The area to change.

Text	Text: The text to display in the text area.


CB_SetModified (Area; Modified)

Sets or un-sets the modified flag for a particular area.  The modified flag is usually set whenever the user makes a change to the text in the area.

Area	LongInt: The area to change.

Modified	Integer: One (1) to set the modified flag or zero (0) to un-set it.


CB_SetEnabled (Area; Enable)

Enables or disables a particular area.  Because of an apparent limitation in 4th DimensionÕs extension interface, a user can click on or tab into a ComboBox area even when it is disabled.  When this happens, the area receives the input focus, but nothing happens.  When an area is disabled, the popup-indicator button changes to the disabled PICT resource.  It is the responsibility of the designer to change the color of the text, if desired, using CB_SetTxtCol.

Area	LongInt: The area to change.

Enable	Integer: One (1) to set enable the area or zero (0) to disable it.


CB_SetHilite (Area; Start; End)

Sets the hilight range of the ComboBoxÕs text area.  This command should not normally be used on an area whose CanEdit flag (see CB_SetFlags) is set to zero (0).

Area	LongInt: The area to change.

Start	Integer: Number of the character after which the highlighting should start.  Zero (0) to start at the beginning.

End	Integer: Number of the character after which the highlighting should end.  

To move the insertion point, call CB_SetHilite with Start and End both equal to the number of the character after which the insertion point should be located.




Information Commands


CB_GetLstRws (Area) -> LongInt

Gets the number of rows an area is set to display in the scrolling list.

Area	LongInt: The area to check.

Returns the number of rows the area is set to display in the scrolling list.


CB_GetLstPos (Area) -> LongInt

Gets the element number currently selected in an areaÕs scrolling list.

Area	LongInt: The area to check.

Returns the element number currently selected in the list.  Note that when the CanEdit flag is set to one (1) (see CB_SetFlags), the text of the selected element is not necessarily the same as the text in the text area even if there is an element in the list with text that matches the text area.  This is true because when the CanEdit flag is set to one (1), ComboBox searches only when the insertion point is at the end of the text.


CB_GetTxt (Area; Text)

Gets the text from the text area.

Area	LongInt: The area to check.

Text	Text: A text variable to accept the text from the text area.


CB_GetModified (Area) -> LongInt

Determines whether or not the area has been modified since it was selected.

Area	LongInt: The area to check.

Returns one (1) if the area has been modified since it was selected.  Otherwise, returns zero (0). 


CB_GetEnabled (Area) -> LongInt

Determines whether or not the area is enabled.

Area	LongInt: The area to check.

Returns one (1) if the area is enabled.  Otherwise, returns zero (0). 


CB_GetHilite (Area; Start; End)

Gets the hilight range of the ComboBoxÕs text area.

Area	LongInt: The area to check.

Start	Integer: Integer variable to receive the number of the character after which the highlighting starts.

End	Integer: Integer variable to receive the number of the character after which the highlighting ends. 


CB_GetFontNum (ÒFontNameÓ) -> LongInt

Returns the Font Number of the specified font.

FontName	String: The name of the desired font.

Returns the font number of the font specified in FontName.  




Update History


1.1.1	Kept ComboBox areas from ÒswallowingÓ the escape key.  This change was necessary to allow the Customizer settings to work properly when the escape key is assigned to the ÒCancel LayoutÓ function.

	Fixed a crashing bug revealed with Charlie RiemanÕs ÒLess-Obnoxious Bus ErrorÓ control panel.

	Fixed a bug that caused some of a layoutÕs text fields to display improperly in the design environment.

	Compiled with better optimizations, reducing the size of the FAT version by about 1K.

1.1 (release)	Added CB_GetFontNum function.

	ComboBox now draws its default appearance in the design environment.

	Fixed crashing problem with CB_SetDefGap.

	Included Demo database from Dan Katz.

 Included Proc.ext-compatible version.  WARNING: Do not include both the ComboBox.Lib and the ComboBox.Ext versions in the same database.

1.1 a2	Made PPC version into a Disk Fragment so it works with 4D x.5.

1.1 a1	Kept ComboBox areas from ÒswallowingÓ the Enter key.

	Fixed a problem of ÒdeadÓ scroll bars with multiple ComboBoxes on one layout.

	Made closing the list window call the ComboBox objectÕs script.

1.0.2	(Maintenance Release) Made PPC version into a Disk Fragment so it works with 4D x.5.

1.0.1	Fixed a problem that caused the list box to remain empty on the screen. Even though typing would choose one of the items, the items never displayed.  This would happen only on occasion, but when it did, it happened for the entire session on that database.

	Fixed a problem where clicking on a non-selectable object (a button, for example) would clear a ComboBoxÕs Modified flag.

1.0	Initial Release





Known Problems and Limitations


1) Disabled areas still receive input focus.  This appears to be a limitation of 4D's extension architecture.

2) When a ComboBox area is used in a modal (type 1) window and the user opens the list, 4D captures any mouse click in the list and beeps rather than allowing a list item to be chosen.  Note that this happens only when the area is in a modal window.

3) The Color popup-indicator PICT resources are used even when the monitor is set to black & white.

4) String comparisons are always diacritical-sensitive and limited to ASCII text.  There are currently no plans to support multi-lingual character sets in the near future.

If anyone finds other problems or knows how to work around these problems, please let me know at Steve_Dwire@linq.pcci.edu.

Thanks,

Steve Dwire


(CodeWarrior is a trademark and Metrowerks is a registered trademark of Metrowerks, Inc. 4D is a trademark and 4th Dimension is a registered trademark of ACI/ACI US.  All other trademarks or registered trademarks are property of their respective owners.)